<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Setting up field and document level security | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'field-and-document-access-control.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/field-and-document-access-control.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/field-and-document-access-control.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/field-and-document-access-control.html" rel="nofollow" target="_blank">../en/field-and-document-access-control.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="secure-cluster.html">Secure a cluster</a></span>
»
<span class="breadcrumb-link"><a href="authorization.html">User authorization</a></span>
»
<span class="breadcrumb-node">Setting up field and document level security</span>
</div>
<div class="navheader">
<span class="prev">
<a href="mapping-roles.html">« Mapping users and groups to roles</a>
</span>
<span class="next">
<a href="run-as-privilege.html">Submitting requests on behalf of other users »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="field-and-document-access-control"></a>Setting up field and document level security<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/field-and-document-access-control.asciidoc">edit</a><a class="xpack_tag" href="https://www.elastic.co/subscriptions"></a>
</h2>
</div></div></div>
<p>You can control access to data within an index by adding field and document level
security permissions to a role.
<a class="xref" href="field-level-security.html" title="Field level security">Field level security permissions</a> restrict access to
particular fields within a document.
<a class="xref" href="document-level-security.html" title="Document level security">Document level security permissions</a> restrict access
to particular documents within an index.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Document and field level security is currently meant to operate with
read-only privileged accounts. Users with document and field level
security enabled for an index should not perform write operations.</p>
</div>
</div>
<p>A role can define both field and document level permissions on a per-index basis.
A role that doesn’t specify field level permissions grants access to ALL fields.
Similarly, a role that doesn’t specify document level permissions grants access
to ALL documents in the index.</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>When assigning users multiple roles, be careful that you don’t inadvertently
grant wider access than intended. Each user has a single set of field level and
document level permissions per index. See <a class="xref" href="field-and-document-access-control.html#multiple-roles-dls-fls" title="Multiple roles with document and field level security">Multiple roles with document and field level security</a>.</p>
</div>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Document- and field-level security disables the
<a href="shard-request-cache.html" class="ulink" target="_top">shard request cache</a>.</p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="multiple-roles-dls-fls"></a>Multiple roles with document and field level security<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/field-and-document-access-control.asciidoc">edit</a>
</h3>
</div></div></div>
<p>A user can have many roles and each role can define different permissions on the
same index. It is important to understand the behavior of document and field
level security in this scenario.</p>
<p>Document level security takes into account each role held by the user and
combines each document level security query for a given index with an "OR". This
means that only one of the role queries must match for a document to be returned.
For example, if a role grants access to an index without document level security
and another grants access with document level security, document level security
is not applied; the user with both roles has access to all of the documents in
the index.</p>
<p>Field level security takes into account each role the user has and combines
all of the fields listed into a single set for each index. For example, if a
role grants access to an index without field level security and another grants
access with field level security, field level security is not be applied for
that index; the user with both roles has access to all of the fields in the
index.</p>
<p>For example, let’s say <code class="literal">role_a</code> grants access to only the <code class="literal">address</code> field of the
documents in <code class="literal">index1</code>; it doesn’t specify any document restrictions. Conversely,
<code class="literal">role_b</code> limits access to a subset of the documents in <code class="literal">index1</code>; it doesn’t
specify any field restrictions. If you assign a user both roles, <code class="literal">role_a</code> gives
the user access to all documents and <code class="literal">role_b</code> gives the user access to all
fields.</p>
<p>If you need to restrict access to both documents and fields, consider splitting
documents by index instead.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="templating-role-query"></a>Templating a role query<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/role-templates.asciidoc">edit</a>
</h3>
</div></div></div>
<p>When you create a role, you can specify a query that defines the
<a class="xref" href="document-level-security.html" title="Document level security">document level security permissions</a>. You can
optionally use Mustache templates in the role query to insert the username of the
current authenticated user into the role. Like other places in Elasticsearch that support
templating or scripting, you can specify inline, stored, or file-based templates
and define custom parameters. You access the details for the current
authenticated user through the <code class="literal">_user</code> parameter.</p>
<p>For example, the following role query uses a template to insert the username
of the current authenticated user:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/role/example1
{
  "indices" : [
    {
      "names" : [ "my_index" ],
      "privileges" : [ "read" ],
      "query" : {
        "template" : {
          "source" : {
            "term" : { "acl.username" : "{{_user.username}}" }
          }
        }
      }
    }
  ]
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1259.console"></div>
<p>You can access the following information through the <code class="literal">_user</code> variable:</p>
<div class="informaltable">
<table border="1" cellpadding="4px">
<colgroup>
<col class="col_1">
<col class="col_2">
</colgroup>
<thead>
<tr>
<th align="left" valign="top">Property</th>
<th align="left" valign="top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p><code class="literal">_user.username</code></p></td>
<td align="left" valign="top"><p>The username of the current authenticated user.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">_user.full_name</code></p></td>
<td align="left" valign="top"><p>If specified, the full name of the current authenticated user.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">_user.email</code></p></td>
<td align="left" valign="top"><p>If specified, the email of the current authenticated user.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">_user.roles</code></p></td>
<td align="left" valign="top"><p>If associated, a list of the role names of the current authenticated user.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p><code class="literal">_user.metadata</code></p></td>
<td align="left" valign="top"><p>If specified, a hash holding custom metadata of the current authenticated user.</p></td>
</tr>
</tbody>
</table>
</div>
<p>You can also access custom user metadata. For example, if you maintain a
<code class="literal">group_id</code> in your user metadata, you can apply document level security
based on the <code class="literal">group.id</code> field in your documents:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/role/example2
{
  "indices" : [
    {
      "names" : [ "my_index" ],
      "privileges" : [ "read" ],
      "query" : {
        "template" : {
          "source" : {
            "term" : { "group.id" : "{{_user.metadata.group_id}}" }
          }
        }
      }
    }
  ]
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1260.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="set-security-user-processor"></a>Pre-processing documents to add security details<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/set-security-user.asciidoc">edit</a>
</h3>
</div></div></div>
<p>To guarantee that a user reads only their own documents, it makes sense to set up
document level security. In this scenario, each document must have the username
or role name associated with it, so that this information can be used by the
role query for document level security. This is a situation where the
<a href="ingest-node-set-security-user-processor.html" class="ulink" target="_top">Set Security User Processor</a> ingest processor can help.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Document level security doesn’t apply to write APIs. You must use unique
ids for each user that uses the same index, otherwise they might overwrite other
users' documents. The ingest processor just adds properties for the current
authenticated user to the documents that are being indexed.</p>
</div>
</div>
<p>The <a href="ingest-node-set-security-user-processor.html" class="ulink" target="_top">set security user processor</a> attaches user-related details (such as
<code class="literal">username</code>,  <code class="literal">roles</code>, <code class="literal">email</code>, <code class="literal">full_name</code> and <code class="literal">metadata</code> ) from the current
authenticated user to the current document by pre-processing the ingest. When
you index data with an ingest pipeline, user details are automatically attached
to the document.</p>
<p>For more information see <a href="ingest.html" class="ulink" target="_top">Ingest node</a> and <a href="ingest-node-set-security-user-processor.html" class="ulink" target="_top">Set security user processor</a>.</p>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="mapping-roles.html">« Mapping users and groups to roles</a>
</span>
<span class="next">
<a href="run-as-privilege.html">Submitting requests on behalf of other users »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>